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Enclosed is Module 6 
Testing and Debugging Made Easy 


In your previous module, you examined what is referred to as the internal 
programming "MAP" of several different processors, coded programs in assembly 
language and reviewed different addressing modes. 


In this module we will show you how to test and debug computer programs. 
Learning to debug a program is essential, particularly if the program is new or 
you are modifying a large program. Very seldom does any one design or modify a 
program with going through one or more test and debugging routines. 


The module begins with a discussion of the most common type of errors 
encountered in programming and shows you how they work their way into programs. 
We then review the procedures used to find the various types of errors. 
Locating and correcting program errors is usually done in two stages: 


* First, we locate spelling and syntax 
errors so the program will compile or 
assemble correctly 


* Now, we can run the resulting machine 
language program and test it for logi- 
cal errors. 


Next, we show you how the debugging process can be made easier and more 
certain by treating the program as a series of functional blocks and testing 
each block by itself, and then in conjunction with adjoining blocks. This 
method allows you to make sure each block is fully tested and errors corrected, 
even if the effect of each block is not easily recognized on the screen. 


To help you understand the way and how of debugging, we have included some 
programs on the enclosed disk that you will examine and modify using your 
"NRIBUG" program. 


Your next module, "Creating Meaningful Documentation" will illustrate how 
a few hours of writing clear documents when the program is designed, will save 
you hours of work at some later date, when you try to modify the design of an 
existing program. We also will cover the different types of documentation as 
well as proven shortcuts. Learn how to prevent making the most common error 
made in programming -- bad or missing documentation. 


Sincerely yours, 


Kenneth J. Bigelow 
Project Engineer 
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Overview for the Commodore 64 and 128 Computers 


CONTEMPORARY 
PROGRAMMING 
AND SOFTWARE 
DESIGN SERIES 


With Module 6, you begin the second half of your 
course in Contemporary Programming and Soft- 
ware Design. In the first half of the Series, you 
followed the development process of a computer 
program from the initial idea or problem, through 
the development of the solution procedure, and up 
to the coding of the actual computer program. 

However, as you write programs of your own, 
you will find that they seldom perform exactly as 
intended the very first time they are run. In fact, you 
might be surprised at the number of tests and 
corrections we must make in our example programs 
on the program disks enclosed with each module in 
this series! Errors appear for many reasons and 
have a number of causes. They must be eliminated 
one by one from a program, until that program 
works correctly in all respects. 

In this module, you will become familiar with 
many kinds of errors that may appear in programs 
of all kinds. Some of these errors are obvious and 
easily spotted, as soon as the intepreter or compiler 
reaches them. Syntax errors or illegal uses of 
operators or variable names will be called out very 
quickly. Other errors are very subtle. They only 
show up after much searching and testing. Reversed 
logic in a mathematical calculation, for example, is 
perfectly legal and will run as written. However, it 
will still give wrong answers to the problem. This 
sort of error usually requires that you trace through 
the program one step at a time, comparing the 
computer’s performance with your manual solution. 

As with all of the program disks you have received 
so far, the enclosed disk is formatted for the 
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Commodore 64 and 128 (in 64 mode) computers. 
We suggest that you use UNI-COPY or BACKUP 
to duplicate this disk, and then use the backup copy 
with this module. Then, in case of an accident, you 
will still have the original disk and can make another 
copy. 

You will also need either NRIBUG or the Fast 
Assembler from Module 5. You will be modifying a 
number of programs using these utilities. 

Now, to begin working with this module, turn on 
your disk drive(s) and computer, and type in the 
commands: 


LOAD “WELCOME?” ,8<return> 
RUN<return> 


When the program directs you to do so, open your 
Learning Guide to the Introduction. You are now 
dealing with one of the most important aspects of 
computer programming: debugging. 
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Testing and Debugging Made Easy 


Whenever programmers develop and code a pro- 
gram, in any language, they always expect to 
spend time correcting errors and adjusting the be- 
havior of the program. Commercial programmers, 
working on very large programs, can find them- 
selves spending more time on this task than on the 
development of new programs. There are many 
reasons for this, and in this module we will explore 
the debugging process, as it is called, and see why it 
is necessary. 

If you have not already done so, turn on your 
computer and disk drives, and type in the com- 
mands: 


LOAD “WELCOME?” ,8<return> 
RUN<return> 


Return to this point when the computer instructs 
you to do so. 
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Typical errors by a single programmer include 
various typographical errors, which cause syntax 
error messages, reversed-logic errors, and individual 
step omissions. With large programs, where a 
number of different programmers can be working 
on different parts of the program, more errors can 
appear when the different parts are combined into a 
single program. 

Of course, we would prefer that there be no 


errors in any program we write. Since this is unrea- 
sonable, we must locate, identify, and correct errors 


in our programs once we have actually coded them. 
As we learn more about the sources of errors, we 
can also learn to avoid making some of them as we 
code our programs. We cannot avoid them all, so in 
this module we will examine the sources of errors in 
programs, and how we can test for them and correct 
them to make our programs work properly. 


cody 
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NOTES: 
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TRACK 1 


HOW ERRORS APPEAR IN PROGRAMS 


Errors can appear in programs in many forms and 
from many causes. Some are easy to spot, and these 
can be eliminated by the programmer during the 
coding process. For example, if you note that you 
have entered the command GUSUB in a BASIC 
program, you may change it right then to GOSUB. 
Other types of errors are less obvious, and are 
harder to locate and correct. To better understand 
the requirements of testing and debugging a pro- 
gram, let’s first see how errors occur, and how they 
appear in a typical program. 


Sector 1: The Typographical Error 


Typographical errors appear in almost any docu- 
ment created through a keyboard. Typical ty- 
pographical errors are missing letters, repeated 
letters, swapped letters, or substituted letters. Most 
of these can be found by a spelling checker. But 
what happens if you type “then” instead of “than” 
or another legitimate word in place of the one you 
meant? The spelling checker will accept it because it 
is a legitimate word. 

Normally, errors of this type will be spotted at 
once by the interpreter, compiler, or assembler. 
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These programs recognize only precise sequences of 
characters, and will not be fooled by others. For 
example, if your BASIC interpreter sees a program 
line that starts with DTAT, it will not recognize it as 
DATA. The interpreter will first try to use DTAT as a 
new variable name that you are just defining. But 
there will be no “=” sign to create this new defini- 
tion, so the statement is incomprehensible to 
BASIC. The result is a “Syntax error in Line xxxx” 
message. Then you can proceed to examine that 
line, correct the spelling of DATA, and RUN the 
program again. 


Sector 2: Errors of Reversed Logic 


Consider the following sequence of instructions in 
BASIC: 
A=B+C 
B=B+1 
If we exchange these two instructions, the resulting 
value of A will be one greater than it would be with 
the present sequence. The final value of A is deter- 
mined not only by the equations used, but also by 
the order in which the individual instructions appear. 


@ 
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This kind of logical sequence applies in many 
places throughout any program. You must be care- 
ful to put every action and command in its correct 
place in the program. Otherwise, what you get from 
your program will be different from what you 
wanted. You must open a file on disk before you 
can access the data in it, you must define a variable 
before you can use it in a computation, and you 
must be careful of how you place parentheses in a 
mathematical calculation. Otherwise, you will get an 
error message or useless results. 

Reversed logic can apply to groups of instructions 
as well as to individual instructions. It can happen 
anywhere in a program. In some cases, the order in 
which operations are performed is unimportant. For 
example, you can usually say A = 0 and B = Oin 
either order, because there is no interaction between 
these two commands. However, if A is to be reset to 
zero for each pass through a program loop but B is 
not, the sequence does become important, and the 
sequence above will be incorrect. 

A second version of reversed logic appears in the 
form of updating a value in the wrong direction. This 
happens in routines that calculate a value by a 
method of successive approximation. For example, 
Newton’s Method for calculating the square root of a 
number uses the formula: 


hee NN 
iene 


where X is a guess at the square root of N, and Xj is 
a better guess. The calculation is repeated with X 
substituted for X each time, until the resulting value 
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of X, is the same as X, or is within an acceptable 
margin of error. The BASIC instructions required to 
implement this operation are: 


100 X = N/2 
110 XO = (X* X + N)/(2 * X) 
120 IF ABS(1 — X0/X) < MAXERROR THEN 200 


130 X = XO 
140 GOTO 110 
po Ae Oe 


We arbitrarily set our initial guess for X as being 
half of our number, N. Other values can also be 
used. This repeated calculation will rapidly converge 
to the correct square root of N. 

Suppose we inadvertently write line 130 as XO = 
X, rather than the code shown above. In this case, 
we will correctly calculate our new guess, XO, but we 
will then wipe it out again in line 130. Asa result, we 
will repeat the calculation endlessly without chang- 
ing the value of X. The error test will not be ac- 
cepted, and BASIC will not leave this loop. 

Once the syntax errors have been removed from 
a program, this type of logical sequence reversal can 
cause some of the biggest headaches for the pro- 
grammer. 


Sector 3: The Missing Line of Code 


It is surprisingly easy to omit one or more lines of 
code from a program as you are coding it. This can 
occur because we think faster than we type. We can 
easily find our minds moving along the program- 
ming form faster than we can type the program 
code into the computer. When this happens, we run 
the risk of bypassing one or more lines of code. 
Similar lines of code placed close together can 
worsen this problem. 
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If you take a break during coding, be sure to 
indicate clearly where you left off, so that you can 
return to the right point. Otherwise, you might leave 
out or duplicate lines of code. Either condition will 
mean improper operation of your program. 

The easiest way to avoid this problem is to make 
the coding process as mechanical as possible. It is 
best to make sure that the entire programming proc- 
ess is performed one step at a time. Do not try to 
design the program while you are coding it, nor to 
code it while you are designing it. As you become 
familiar with the programming process you can start 
taking shortcuts, but don’t do so now. 

While you are designing a program, you may 
wish to turn to the computer and see how a particu- 
lar instruction sequence might work. However, this 
is an experimental procedure, and is not considered 
part of the actual coding process. 


Sector 4: Errors Caused by Improper Use of 
the Program 


This type of error occurs when the data provided 
to a working, corrected program is invalid for that 
program. The data may or may not be accepted to 
begin with, but cannot be processed according to 
the program procedures. 

For example, consider the square root calculation 
routine described earlier. If you give it an initial value 
of 9 for N, the initial guess will be 4.5. The next 
guess will be 3.25, and the third guess will be 
3.0096153 . . . . while the fourth guess will be ap- 
proximately 3.0000153. As you can see, this series 
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converges quickly to the correct answer. What hap- 
pens if you use a negative value for N? In this case, 
there is no real square root to calculate. The se- 
quence will not converge, but will alternately pro- 
duce positive and negative approximations, and will 


_ continue to bounce back and forth. 


An initial N of 0 will cause a problem, even 
though the series does converge toward 0, which is 
the correct answer. Unfortunately, as soon as a 
guess of zero is tried, the denominator becomes zero 
and we get a “/O Error” or the equivalent. 

Similar problems can occur if you input a char- 
acter string when your program expects numbers, or 
if your character string contains illegal characters in 
it. Depending on the nature and purpose of your 
program, invalid input data may cause results rang- 
ing from invalid results to a complete lockup of the 
computer. There is a risk of this problem happening 
anytime the data input to a routine exceeds the 
intended range or type of input data. 
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NOTES: 
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TRACK 2 


LOCATING AND CORRECTING ERRORS IN 


A PROGRAM, PART 1 


Now that we have some idea of how errors can 
occur in a program, we need a method for locating 
these errors and identifying them so that they can 
be corrected. Some errors can be found by the 
computer, while others require careful testing and 
analysis. Before you can call a program finished, 
you must test it thoroughly and eliminate all errors. 

The testing process begins with an attempt to 
compile or assemble your program and then run- 
ning it. If you use an interpretive language such as 
BASIC, compiling is unnecessary. If you use a com- 
piler language, the first stage of testing is merely to 
compile the program. The compiler itself will report 
a number of different kinds of errors, as will an 
assembler. These are mostly syntax errors, which 
are reported by BASIC as you attempt to RUN a 
program. 

NOTE: In order to effectively complete this Track 
you should have your computer available. If your 
computer is not available at this time, repeat this 
Track when you can observe the results of various 
activities on your computer. 
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Sector 1: First-Round Errors 


To see what may happen the first time you RUN 
a BASIC program, type in the commands: 


LOAD “TRACK2” ,8<return> 
RUN<return> 


This program has not been debugged, and you will 
find an error message on your screen. 

LIST the offending program line with the LIST 
command, and look it over Can you spot what 
BASIC didn’t like? Do you see any other errors in 
this program line? If so, correct them as well. Then 
RUN the program again. 

You will receive a number of different error mes- 
sages from this program. In each case, try correcting 
the error as you think best. Possibly the most diffi- 
cult type of error to correct at this point is the 
“Unlisted Line Number” error, or its equivalent. 
This error occurs when you have a GOTO or 
GOSUB to a destination line number that does not 
exist in the program. Sometimes, if you have just 
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finished coding the program, you can determine the 
intended destination of the instruction, and insert it 
at once. If you did not write the program, or if you 
are testing it a week after coding it, the problem is 
more difficult. In this case, can you determine from 
the program listing where this GOTO is intended to 
go? 

If you can you’re doing extremely well. We have 
deliberately left out all comments and indications of 
what each section of code does. You have only the 
code itself to provide indications of where the GOTO 
instruction should transfer control in order to oper- 
ate the complete loop. 

The correct destination for this particular GOTO 
instruction is line number 510. Line 500 initializes 
the variable I, and must be executed only once. Line 
510 then increments I, before it is printed out. If you 
set the GOTO instruction to transfer control to line 
500, the program will constantly reset I to 0 before 
adding 1 to it. As a result, the terminal value of 10 
will not be reached, and the loop will continue to 
display the number 1. 

The final error in this program is similar, but is not 
noticed at once. Suddenly, you find the program 
repeating the same sequence of text lines. Each time 
you hit a key as requested, you get the same mes- 
sage. 

This type of error can easily appear in versions of 
BASIC which permit full-screen editing of the pro- 
gram. In this editing mode, you can use the cursor 
keys to move the cursor anywhere on the screen, 
and to modify program lines on the screen. You can 
also duplicate program lines by typing a new line 
number in place of the existing line number. This will 
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not eliminate the original line, but it will enter a 
duplicate line with the new line number. 

Many of the duplicate lines in programs on your 
program disk were created in exactly this way. The 
delay loop: 


FOR I=1 TO 2000:NEXT I 


is the most common example of this. In key loca- 
tions, we also edit the 2000 up to 5000. 

Once you have corrected all of the first-round 
errors in the program, so that the program at least 
RUNs without producing spontaneous error mes- 
sages, be sure to SAVE the program to disk. You 
might use a filename such as TRACK2A to show 
that this is the modified version of TRACK2. You 
can then proceed with the second-round tests on 
program performance. 


Sector 2: First Round Tests on Compiled 
Programs 


When you ran the TRACK2 BASIC program, you 
corrected each error as it appeared on the screen. It 
worked this way because the original BASIC source 
code remains in memory, and is interpreted in se- 
quence by the BASIC interpreter. When an error is 
found, the interpreter stops, signals the error, and 
drops into command mode. You can correct the 
error and RUN the program again. 

With a compiler language, the procedure is 
slightly different. You must take the complete source 
code and feed it to the compiler. The compiler scans 
the entire source program, often more than once, 
and attempts to generate the equivalent object 
code, or machine language program. If the compiler 
finds an error that it cannot resolve, it reports that 
error and stops generating object code. It continues 
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scanning the source program for other errors. Any 
such errors will also be reported. 

If the compiler reports errors in your source pro- 
gram, any object file it might have generated will be 
flawed and unusable. You should erase it from disk 
or ignore it, if it is still in memory. Instead, take the 
list of errors produced by the compiler, and go 
through your entire source program. Correct each 
error as you reach it, and then try to compile the 
corrected program again. When the program com- 
piles without any error messages, you can proceed 
to make the second round of tests. 

Often a compiler will scan a source program more 
than once. Each scan of the program is called a 
pass. The compiler does different things on different 
passes, so that it can compile the object code cor- 
rectly. For example, on the first pass it may look for 
all program lines that are referenced by other pro- 
gram lines. When it goes on to the second pass, it 
will know where to go for forward jumps or other 
forward references. 

Since the compiler does different things on differ- 
ent passes, it may find errors during one pass that it 
missed on a previous pass. The first round of error 
checking and correction is not considered over until 
the program compiles correctly and produces a 
complete object file. 


Sector 3: First-Round Corrections for 
Assembly Language 


A program written in assembly language has 
many characteristics in common with a program 
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written in a compiler language. Like a compiler, an 
assembler scans through the entire source code and 
attempts to convert it as a whole to machine code. 
Most assemblers scan the source program twice, 
decoding the instructions on each pass. During the 
first pass, the assembler determines the address that 
corresponds to each label in the program. During 
the second pass, the assembler substitutes that ad- 
dress each time it finds the specified label. 

As with compilers, assemblers will report all errors 
they find during the assembly process. The pro- 
grammer locates and corrects all of them, and then 
tries to assemble the program again. Syntax errors 
are not uncommon during the first assembly run, 
and are usually caused by typographical errors, just 
as with compilers and interpreters. 
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Other-errors that may be detected by the as- 
sembler are somewhat different than for higher-level 
languages. Typical errors found by assemblers are: 


@ Undefined Symbol. A label or other symbol 
has been used as an operand, but has not ap- 
peared in the label field to be defined. 

Illegal Addressing Mode. The addressing 
mode you specified for an instruction cannot be 
used with that instruction. 

Phase Error. A label appeared at a different 
address during Pass 2 than it did during Pass 1. 
This normally indicates that an earlier instruction 
was specified as having a short operand, but was 
later found to require a long operand. That 
change will already have been flagged as an error. 
Out of Range. The destination of an explicitly 
short jump was too far away to be reached. This 
may cause phase errors later in the program. This 
error may appear for any instruction using a PC- 
relative addressing mode. 

Overflow. The operand for an instruction re- 
quires more bits than the specified register or 
memory location can hold. Most assemblers will 
accept signed or unsigned numbers either 8 or 16 
bits long. They still cannot fit 9 bits into an 8-bit 
register, and will object if the programmer tries to 
do so. 


Other error messages and warnings are also pos- 
sible, and will vary from one assembler to another. 
Most are self-explanatory, but you should refer to 
the assembler manual for details regarding each 
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error message and the precise requirements of that 
assembler. 

As with compiled and interpreted programs, the 
first step with an assembled program is to get the 
assembler to accept the entire program. Once the 
program assembles with no error messages, you can 
continue to the second round of the testing and 
debugging procedure. 


NOTE: Some assemblers directly produce a 


.COM file as their output. This file may be executed 
directly. Others may produce a relocatable object file 
with an extension of .OBJ or .REL instead of .COM. 
This allows multiple object files to be linked together 
into a single machine-language file. This is done 
with a second program (usually called LINK or L). In 
the IBM PC and PC compatibles, the linked file has 
an extension of .EXE, and can be executed directly. 


If the linked file fits into a single 64K segment and 
meets certain other criteria, you can use a utility 
called EXE2BIN to convert the .EXE file to a .COM 
file, which requires less room on the disk. 

Assemblers for Z-80 processors, especially those 
operating under CP/M, generally produce a .HEX 
file (each byte of object code is specified as two hex 
digits), which is converted to a .COM program with 
the LOAD utility. Other assemblers will have other 
procedures, according to the requirements of the 
processor and the operating system. You should 
always refer to the assembler manual for informa- 
tion on such details. 

Regardless of the language in which your pro- 
gram was written, once it will compile, assemble, or 
run under an interpreter without any error mes- 
sages, you have completed the first round of tests 
and corrections, and you are ready for round two. 
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TRACK 3 


LOCATING AND CORRECTING ERRORS, 


PART 2 


Once all of the syntax errors, wrong jump destina- 
tions, incomplete instructions, and other such errors 
have been found by the compiler, assembler, or 
interpreter and have been corrected, you will be 
ready for the next stage of program testing. At this 
point, the program will compile (or assemble), or the 
interpreter will not find any more first-round errors. 
That does not mean that the program will neces- 
sarily work correctly. Keep in mind that the com- 
puter will always do what you say, as opposed to 
what you may mean. 

It is now time to run the program using selected 
data, to see if the program will produce the right 
answers. If the program is numerical, you can test it 
by feeding in easy-to-check numbers, and compar- 
ing the program’s results with the results you obtain 
by hand. For example, if your program calculates 
square roots, have it find the square roots of num- 
bers such as 1, 4, 9, and 16. If it gets these right, go 
on to more difficult numbers that still have known 
answers, such as 2, 3, and 5. 

If you have a sorting routine, test it with a list of 
single letters or numbers first, and then go on to 
longer numbers or character strings. Continue until 
you can be reasonably sure that the program is 
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doing what you intended. Then you can be sure that 
the program will also operate correctly with un- 
known input data. 

As a general rule, unless your program is 
intended only for your own use, you should assume 
that someone may take it and misuse it. You should 
arrange your program to survive such usage without 
going haywire, especially if you are writing a pro- 
gram for commercial use and sale. 

Regardless of the nature of the program, you can 
follow a generalized testing procedure to locate log- 
ical faults in a program. Once such a bug is located, 
you can correct it. The general procedure is essen- 
tially the same for all kinds of programs, but the 
specific techniques will depend on the nature of the 
program. To see how this all ties together, let’s con- 
sider some of the general rules for testing, and apply 
them to some specific instances. 


Sector 1: Testing Numerically Oriented 
Programs 


Any program that deals primarily with numbers is 
numerically oriented. Such programs are used in a 
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wide range of applications, from the calculation of a 
student’s grade point average to keeping track of 
rockets and satellites. 

In general, numeric programs fall into the overall 
category known as Data Processing, or DP. The 
data to be processed may fall into several fields of 
endeavor, including technical (scientific) fields, ac- 
counting, industrial control and monitoring, etc. All 
of these fields, and many others, use computers to 
keep track of various input signals or data, process 
this data in some fashion, and then produce answers 
based on the outcome of the calculations. 

The intended processing function may need to be 
carried out in real time, while the actual process is 
going on, and keeping up with it. If so, some extra 
timing tests will be required (more on that later in 
this Track). Either way, the general tests for correct 
program operation are essentially the same. 


The first step is to select a set of input numbers for 
which the output result of the program may be 
readily determined with pencil and paper. Numbers 
such as 0, 1, and 2 are typical choices. Often, you 
can simplify the calculation, especially for the first 
few tests, by setting some of the input variables to 
values that will cause them to have no effect on the 
result of the calculation. In this way, you can simplify 
your task at the beginning by having some variables 
drop out of the test while you are checking the effect 
of other variables. 

In addition, the numbers O and 1 are especially 
useful in locating some kinds of program buas. 
Thus, problems such as division by zero or the 
unwanted disappearance of critical data can often 
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be uncovered using these numbers for testing pur- 
poses. 

Once you have located and corrected any errors 
dealing with the simplified problems and tests, as- 
sign reasonable, typical values to each of the vari- 
ables. They may still be artificially simple, but they 
should not be unreasonable in magnitude. Repeat 
the program run and again compare the program’s 
results with your hand calculations. If you find any 
discrepancies, track them down and correct them, 
and continue with the tests. 

If your variables become negative, be sure to test 
the program using negative values. If negative or 
zero values are forbidden, make sure that the 
program includes the capability to recognize and 
reject such input, or that such input cannot possibly 
occur in real situations. Recognition is preferred, 
since you cannot necessarily guarantee that some 
computer operator or user will not accidentally type 
in such a forbidden value. You should know how 
your program will behave, and be prepared for it. 
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Always prepare for improper or incorrect inputs, 
and be ready to do something about such entries. 

If at any time your calculated results do not match 
the results produced by the program, go back to 
your program source code, and go through it line by 
line, determining exactly what the computer will do 
for each step. If you are not sure just what the 
computer will do in response to a particular instruc- 
tion, write a brief program to find out. It is not 
enough to expect the computer to behave in a cer- 
tain way; you must know exactly how it will behave. 
Otherwise, you will not know where or why it is 
misbehaving. 

Be especially careful with real numbers repre- 
sented in floating-point format, and with transcen- 
dental functions such as logarithms, exponentials, 
and trigonometric functions. You will be displaying 
your results in decimal notation, but the computer 
will be operating in binary. Exact conversions back 
and forth are not always possible, so you can expect 
roundoff and truncation errors that must be han- 
dled. We ran into this exact problem with the LOAN 
program in Modules 1 and 2. To observe this prob- 
lem in action, type in the BASIC command line: 


FOR I=1 TO 10 STEP .01:PRINT I:NEXT I<return> 


This sort of error is not a program flaw as such, but 
does require some “fixing up” in most cases. This is 
done by rounding off numbers as they are calcu- 
lated, so that all numbers at the start of any calcula- 
tion have only the desired degree of precision. That 
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way, we eliminate the cumulative effect of repeated 
truncation and roundoff errors. 

When you are sure that the program handles 
numbers and interactions between numbers cor- 
rectly, and that any problems of mishandling have 
been solved, then you can assume that the program 
will handle other numbers correctly as well. 


Sector 2: Testing String-Handling 
Capabilities 


When a program must deal with character strings, 
several factors must be taken into account. For ex- 
ample, the maximum length allowed a character 
string must be specified. In addition, the number of 
character strings to be dealt with at any time must be 
known. The third factor that must be known is the 
range of characters that will appear in any string. 

Character strings can have a wide variety of pur- 
poses. Typical character strings are names and ad- 
dresses, company names, etc. Phone numbers and 
zip codes might be stated in either numeric or string 
form. Because such codes often include letters as 
well as numbers, they are generally handled as 
strings. This presents no problems for either sorting 
or selecting them, since strings can be handled read- 
ily in such operations. Money is always handled as 
numbers, so that dollar amounts can be added and 
subtracted. 

When you test a program that was designed to 
handle character strings, you should make two basic 
sets of tests. First, test the operation of the program 
in terms of legitimate inputs and manipulations. The 
program should work correctly when all the strings 
to be handled are of maximum length. The charac- 
ters in the string should be handled correctly, so long 
as they are within the range of ASCII codes specified 
for the particular string. For example, if a string is to 
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handle all uppercase letters, then all such letters 
should be handled correctly, from A to Z. 

You should be able to change the contents of any 
string without changing the validity of the program 
and without disturbing the normal progression of 
the program. 

When you are satisfied that your program works 
correctly with correct and proper data, go back and 
test it again with improper data. What does the 
program do if you try to enter a character string that 
is longer than the program is designed to handle? If 
the program is designed for uppercase and lower- 
case letters only, what does it do with digits? What 
does it do with characters such as [, \, ], *, and_, all 
of which have ASCII values between the uppercase 
alphabet and the lowercase alphabet? Are spaces 
allowed? 

Typical responses of an incorrectly designed pro- 
gram to these illegal situations are to ignore excess 
characters and continue as if they were not there, to 
overwrite earlier characters with the excessive ones, 
or to try to handle invalid characters as if they were 
valid. You might deliberately have the program ig- 
nore excess characters, but the other responses are 
undesirable. 

In other cases, programs which receive too many 
strings or too long a string, or too many total string 
characters, may “bomb out” or get lost. You may 
find yourself back in the operating system. More 
often the computer seems to go to sleep, and will 
not respond to the keyboard. In such cases, the 
computer must either be reset or else turned off and 
then on again, in order to regain control. 
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Interpreted languages such as BASIC generally 
catch such conditions and issue an error message 
instead of losing control. A compiled or assembled 
program cannot automatically detect such problems 
in all cases, so your program must specifically check 
for invalid conditions. 

One factor to watch for is the way your program 
handles uppercase and lowercase letters. The ASCII 
codes for the different cases are different, and upper- 
case letters come first. This means that in a sorted list, 
all strings beginning with an uppercase letter will be 
placed before any strings beginning with a lower- 
case letter. In order to prevent this, you must have 
your sorting routine translate all lowercase letters to 
uppercase, at least for the sorting process itself. 
Then, the original lowercase strings can be placed 
back into the sorted list. This may mean the need for 
a duplicate set of strings that are all uppercase, so 
the sorting process will work correctly. 
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Sector 3: Testing File-Handling Operations 


When a program deals with disk files, it must be 
able to perform several operations. In general, these 
operations may be placed into four categories: 
Open the file, Read from the file, Write to the file, 
and Close the file. Each operation should be tested 
carefully, according to the requirements of the pro- 
gram. 

Sequential files are usually easier to visualize than 
random-access files. With sequential-access files, the 
program can simply read or write one record at a 
time, regardless of its length. Records are available 
in sequence, and must be handled in that sequence. 
The disadvantage is that you cannot go back and 
reread an earlier record — to do that you must close 
the file and reopen it, whereupon you will find your- 
self back at the beginning of the file. 

In addition, sequential output files cannot simply 
be updated. When you open a file for sequential 
output, the existing file by that name, if any, is 
erased. Some languages permit an output file to be 
opened for appending rather than restarting, but 
you still cannot modify existing records within the 
sequential output file. You can open a sequential file 
for reading or writing, but not for both. 

To allow a file to be opened for both reading and 
writing, you must use random access techniques. 
This allows you to open a file, check for any desired 
record, update that record, and close the file, with- 
out having to read the whole file or write a whole 
new file back to disk. When you do this, you must 
keep track of the exact structure of the file, because 
the operating system cannot do so. 
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Whenever you open a file for sequential input, it 
must already exist on the disk. If it does not exist, the 
system will respond with some sort of error indica- 
tion. Any program designed to read a file from disk 
must take this possibility into account, and must 
respond appropriately. In BASIC you will get a File 
Does not Exist error and fall into command mode. 
This means that the program has halted and cannot 
be resumed. It would be far better for the program 
to warn the user that the file does not exist, and to 
allow the user to either change disks or to select an 
alternate filename. 

You may want to check for the existence of a file 
before you open it for sequential output. Remember 
that the original file will be erased as soon as it is 
opened, and that you will not be able to recover it. 

When testing a program’s use of sequential files, 
make sure that all possible combinations of events 
are accounted for, and that the program will react in 
each case the way you want it to. If an input file 
already exists, fine. If an output file does not already 
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exist, there should be no problem. If your desired 
output file already exists, the program should report 
this fact and request confirmation, unless the pro- 
gram is so arranged that this is not necessary. 

It is better that a program should report that the 
specified input file does not exist, or that it initialize 
itself for a new file, rather than allowing it to “bomb 
out” and return to the system. Check all possible 
combinations of conditions carefully, to ensure that 
your program will behave correctly under all circum- 
stances. 

If you are dealing with random-access files, you 
have more freedom. When you open a file for ran- 
dom access, you can select any record, and you can 
read or write records in any order. Even if the file 
exists when you open it, it will not be erased. If it 
does not exist, it will be created. 

Because of this, you do not run the risk of destroy- 
ing an existing file the way you do when you open a 
file for sequential output. By the same token, your 
program must be far more careful about how it 
works with the file. Once you write a record to the 
file, you cannot recover the old record. Make sure 
that your program reads and writes records within 
the file in the correct sequence. 

In many languages, only one record can be held 
and worked on at a time. You must allocate appro- 
priate variable space if you must exchange records, 
compare them, or deal with more than one record at 
a time. As with programs using sequential-access 
files, make sure that your program will not, under 
any circumstances, overwrite data that it will need 
later on. 
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One possible remaining problem exists whenever 
you write to a disk file: you may at any time run out 
of disk space. This is often a problem if you keep 
large data files on floppy disks. Even hard drives 
have certain limits on data space, since they are 
generally “partitioned” into logical drives for more 
efficient utilization of space. To avoid problems, 
make sure that your program does not fall asleep if 
this should happen. Make and keep backups of 
important programs and data files, so that your 
losses will be minimized in case this problem should 
crop up; and be assured that it will, when you least 
expect it and cannot afford to lose your data. 

If you can get your program to keep its data and 
allow you to insert a new, formatted disk to save 
your remaining data, do so. Make sure that your 
program will warn you of the problem and allow 
you to correct it, rather than issuing a Disk Full error 
message and dropping out. As with other possible 
error conditions, test your program thoroughly, so 
that you will know exactly what it will do under all 
possible circumstances. You can adjust the program 
as needed to prevent it from losing data at a critical 
moment. 


Sector 4: Checking for Sufficient Memory 


Compiled programs generally include code that 
checks the amount of memory available to the pro- 
gram, and halt the program if the available memory 
is insufficient. Interpreted languages such as BASIC 
simply issue an error message if you should run out 
of memory space. Assembly-language programs do 
not automatically make such a check. If there is any 
possibility that you may run out of memory, you 
must make the test. 

When deciding how much memory your program 
needs, remember that there is more to be concerned 
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with than just the program. You must also allow 
space for any data you will be dealing with, as well 
as buffer space for any files that will be open. All of 
these space requirements are established as part of 
the program design, and can be precalculated or 
readily determined. 


If you don’t allow for stack requirements, a 
number of problems may occur. If the stack may be 
placed anywhere in RAM, it can overwrite data, 
character strings, or even the end of the program. In 
the Commodore computers (6502 processor), the 
stack is always in Page 01. This limits the stack to 
256 bytes, or 128 addresses. If you exceed this limit, 
the stack will “wrap around” to the top of Page 01, so 
that new addresses and data will overwrite older 
addresses. This may cause many kinds of computer 
misbehavior. 


If you don’t allow sufficient room for your stack, 
data on the stack can overwrite your working data or 
even your program. The result can be any number 
of strange responses that may be substantially de- 
layed beyond the time the damage actually oc- 
curred. This sort of “time bomb” can manifest itself 
at any time. For example, in many cases the stack 
briefly overwrites the very end of the program. The 
program works fine until you try to end it, at which 
time the computer tries to execute the addresses 
from the stack instead of the original instructions. 
The most common result is that the computer must 
be reset. 

Other possibilities include changes in character 
strings and constant data that often appear at the 
end of a program, or strange changes in file data 
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after buffers have been allocated. You may find your 
program calling a service routine to read a record 
from your file, and having that record overwrite the 
stack. Then you have lost your return address, and 
the program will bomb out. 

In order to avoid problems of this kind, make sure 
that your program allocates separate memory areas 
for separate tasks, and that there will be no overlap 
between them. 


Sector 5: General Considerations 


The main purpose of the testing process is the 
same for any type of program operation: make sure 
that the program behaves correctly during intended 
operations, and that it rejects or ignores improper 
inputs or results. 

At this point, don’t worry about adding things you 
would like to see in your program. Rather, make 
sure that the present program performs correctly. 
Go back and correct any actual errors, and recom- 
pile or reassemble as necessary. Later on you will 
have time to “fine tune” your program. 

As you test your program, always allow for Mur- 
phy’s Law: anything that can go wrong eventually 
will. There is always a user out there, we call him Mr. 
Watson, who delights in making a program mis- 
behave. He will look for ways to cause problems. 
Accordingly, you should look for such problem 
areas and clean them up before Mr. Watson can get 
to them. If you adopt this philosophy, you will find 
that your completed programs will provide long and 
trouble-free service. 
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PATCHING ERRORS IN COMPILED CODE 


Up to this point, we have assumed that any error 
in a compiled program will be corrected by modify- 
ing the source code and then recompiling it. This is 
not always convenient. Sometimes, at least for test- 
ing purposes, we would like to be able to go into the 
compiled code and make just one change, so that 
we can run the program again without going 
through a long procedure. To do this, we must take 
a look at the actual code produced by the compiler. 

Because a compiler produces machine code that 
can run on its own, it must supply more than just the 
code equivalent of the source program. It must also 
provide any and all subroutines that may be re- 
quired to execute that program. 

For example, if a program uses logarithmic or 
trigonometric functions, the subroutines to perform 
these operations must be inserted by the compiler. 
The programmer need not be concerned with them. 

This added subroutine package may show up at 
either the beginning or the end of the actual user 
program. This not only increases the size of the 
program, but also means that we will have to hunt 
for the actual user program code. We want to be 
sure that we get the actual user code, and that we do 
not modify the added subroutine package. 
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To show how we might modify the compiled 
object code while avoiding the “library subroutines” 
added by the compiler, we have included both the 
source code and compiled object code of the same 
program in a compiler version of BASIC on the 
enclosed program disk. You will not need any 
compilers or interpreters to complete this track. 
However, you will need your computer and 
NRIBUG to examine the object code produced by 
the compiler. 

The compiled program is intended to print the 
text phrase: “Hello, World!” to the screen. This is of 
course a very simple-minded program, but it will 
serve to illustrate the operation of the compiler 
program. 

Of course, many different compilers, recognizing 
a wide assortment of languages, are available for the 
Commodore computers. The C128, using the 
CP/M operating system, has access to many more. 
However, all compilers will follow the same general 
pattern, even though the specific code produced will 
be different for each individual compiler. 
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Sector 1: Compiled BASIC 


The BASIC version of our program was compiled 
using SPRINT, which is the BASIC compiler pro- 
gram listed in the January 1986 issue of COM- 
PUTE!’s Gazette magazine. This is the same issue 
that listed the Fast Assembler which we modified 
and included in Module 5. We named the program 
HELLOB to indicate that it was coded in BASIC. 
Figure 4-1 shows the source code used (HELLOB- 
-BAS on the disk). This source program is quite 
short, and occupies far less than one full block on 
the disk. However, as you can tell from the directory 
listing, the compiled version is substantially longer. 
This program (HELLOB.COM) uses 5 blocks to do 
the same job. 

Actually, the compiled version requires less total 
space than the interpreted version. Keep in mind 
that the compiled version does not require the 
interpreter to be present in memory. Thus, we have 
a 1.25 k-byte program instead of a 35-byte program 
and an 8K (or more) interpreter. Thus, the compiled 
version actually does not require as much memory 
as the interpreted version. 

To verify that the COM program works cor- 
rectly, type in the commands: 


LOAD “HELLOB.COM” ,8,1<return> 
RUN<return> 


to run the compiled program. You should see the 
display “Hello, World!” as you would with the 
regular BASIC program. In any case, the string 
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should be correct. This program requires that the 
Fast Assembler not be resident. If FAS is present, 
turn your computer off and then on again, and try 
the program again. You will need to use NRIBUG 
rather than FAS to examine this program. 

To examine the compiled BASIC version under 
NRIBUG, load NRIBUG if necessary, and then type 
in the command: 


SYS 38870<return> 


When you see the register display, examine the 
contents of memory beginning at location 0800 hex. 

This program starts with a one-line BASIC 
program. If you were to LIST the program HEL- 


LOB.COM, you would see: 
10 SYS2061 


Converting the decimal number 2061 to hex, we find 
that it refers to address 080D. This is why FAS 
cannot be present to run this program; SPRINT has 
already placed it at the beginning of the original 
BASIC workspace. 

Refer to Figure 4-1. Beginning at address 0800, 
the M display of NRIBUG shows a null (placed there 
by BASIC to mark the start of the program), the 
16-bit address (080B) of the next program line, if 
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Figure 4-1. The first 32 bytes of HELLOB.COM. 
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any, and the 16-bit line number of this program line 
(000A). Next we find the byte 9E, which is the 
BASIC token for the SYS command. The next four 
bytes are the ASCII codes for the digits 2061. 
Following this number we find three nulls. The first 
one marks the end of this program line, and the next 
two tell BASIC that there are no more lines in the 
BASIC program. If another line were added, these 
two nulls would be replaced by the address of the 
next program line, just like the address at location 
0801. Thus, as far as BASIC is concerned, this is 
nothing more than a very short program. 

However, there is additional code following the 
three nulls. This is machine language, beginning at 
location 080D. This is the code that will be executed 
by the SYS command. In fact, this is the compiled 
program. Use the D command of NRIBUG to 
examine the code. Make no effort to modify this 
code; this is the run-time code which will be included 
with any compiled program to take the place of the 
BASIC interpreter. It is this code that makes the 
compiled program occupy 5 blocks on the disk, 
rather than just one. Figure 4-2 shows the first 
section of this code. 

Scanning through the code, we find that it is 
essentially all machine language, without buried 
character strings. However, there is one character 
string, which we can find if we use the M command 
repeatedly to locate and display the end of the 
compiled program. Doing this, we find that the last 
byte of the program is located at 0C60, and that 
several lines of M display prior to this location 
remain on the display. Thus, we can see the ASCII 
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Figure 4-2. The first screenful of code for 
HELLOB.COM. 


string “HELLO, WORLD!” starting at location 
0C44, as shown in Figure 4-3. 

Although we cannot change the run-time exe- 
cution code, we can change the character string 
itself. For this demonstration, we’ll change the string 
to “HI, EVERYONE!” . This is still a 13-byte string, 
so it should work correctly. Move the cursor to the 
“48” in the line starting with address 0C40, and 
change the last four hex bytes on this line to 48 49 
2C 20. Press the <return,> key to enter these 
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Figure 4-3. The end of the compiled code, with 
the character string. 


changes and then change the entire next line to 45 
56 45 52 59 4F 4E 45 and press the <return> key. 

In making this sort of change, you can change the 
contents of character strings, but you cannot 
change their lengths. Also, if you can locate and 
identify numeric constants within a program, you 
can change them this way. In each case, be sure to 
verify your change by testing the modified program. 
To do this now, first return to BASIC with the X 
command, and then RUN the program. The com- 
puter should respond by typing HI, EVERYONE!, 
and then displaying the “READY.” prompt. At this 
point, you can SAVE the program to disk as a 
modified version of the original program. 

As a further exercise, and practice in making 
minor adjustments of this nature to compiled 
programs, try modifying the character string one 
more time, to say “HELLO, FOLKS!” when the 
program is run. Test the operation of the program 
and satisfy yourself that it works correctly. 


Sector 2: Patching an Assembled Program 


As we mentioned earlier, most compilers automat- 
ically include a large subroutine package with the 
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actual working program. As you saw with compiled 
BASIC, the subroutine package can be much larger 
than the working program itself. Because of this, 
short and simple programs are better written in 
assembly language. Then, you can leave out all of 
the subroutines you don’t need. 

In the case of our “Hello, World!” program, this is 
certainly the case. In Module 5, you worked out a 
method of outputting a character string to the 
screen, by the use of a JSR instruction through one 
of the jump vectors provided at the top of ROM. The 
same method will work here. Therefore, we can 
design a very simple routine that will perform this 
task. We will have to take a few precautions 
regarding the character string, but we certainly 
won't have to include all of those extra subroutines! 

The assembly-language program (see Figure 4-4) 
is quite simple and direct. It uses exactly the same 
technique that we learned in Module 5 to display a 
character string. The only item that looks different 
from the compiler language source programs is the 
character string itself. The “HELLO, WORLD!” 
string is the same, but we have added some extra 
characters to the end of it. Let’s look at these 
characters, and see why we need them. 

The first character is 0DH. This is a control 
character within the ASCII code, and is identified as 
CR. This means Carriage Return, and is in fact the 
same code that is produced when you press the 
<return> key. This code causes the cursor to 
move back to the left edge of the screen. 


Depending on the particular computer and 
operating system we are using at the moment, we 
might next include the character 0AH. This is 
another ASCII control code, known as LF. This is 
the Line Feed code, which moves the cursor down 
one line on the display. In the Commodore com- 
puters, this code will be automatically included 
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Figure 4-4. The assembly-language version of “HELLO, WORLD!’ 


following any CR code, so we need not include it in 
our string. 

Finally, we have a null character, or 00. This 
character marks the end of the character string. It 
will not be printed, but must be included. Otherwise, 
the routine will continue to print out the contents of 
memory, whatever they may be, until it either finds 
a null character somewhere or has output 256 
characters. 

The inclusion of CR (and sometimes LF) corre- 
sponds to the fact that we used no ending punc- 
tuation in BASIC. The computer is being told to go 
to the start of the next line after displaying the string. 
These characters accomplish that purpose. 


Having written this program in assembly lan- 
guage, we must assemble it. We could use an 
assembler, but this is so short we can either 
assemble it by hand, or else use NRIBUG to enter it 
directly. For practice, let’s assemble it by hand, 
using the op code charts of Figure 1-7 from Module 
5. Refer to Figure 4-5. 

We start by assigning an arbitrary address of 2000 
to the first instruction. From the main op code chart, 
we find that an immediate LDY instruction has an 
op code of AO. Also, we know that we will need one 
more byte to specify the new content of Y, which will 
be 00. Thus, the next instruction will start at address 
2002. 
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Figure 4-5. Beginning to assemble “HELLO, WORLD!” by hand. 
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This is an LDA instruction, using indexed ad- 
dressing through the Y register. It will require three 
bytes, as shown in Figure 4-5. Therefore, the next 
instruction will start at 2005. However, we do not yet 
know the address of the string itself, so we simply 
mark the space it will occupy. We will go back later 
and fill in this information. This is a normal re- 
quirement for any assembly process, when a 
forward reference is encountered. 

The BEQ instruction at location 2005 is used to 
recognize the null at the end of the character string. 
It also has an unknown operand, since we do not yet 
know the address of EXIT. However, we do know 
that the operand will be only one byte long, so we 
mark its space, and assign an address of 2007 to the 
JSR instruction. If you have available the address of 
the character output routine in the jump table, you 
can insert it now. If not, mark the space for a 
two-byte operand (address) following the op code of 
20H. In any case, this will place the next op code at 
address 200A. 

Here, we have an INY instruction to step our 
pointer to the next character in the string. This 
requires only the op code, C8H. Therefore, we can 
write this code into the programming form and 
assign an address of 200B to the next instruction. 

At this point, we are ready to go back to fetch the 
next character to be output. However, the 6502 
instruction set does not have an unconditional 
branch instruction. We could put a JMP instruction 
here, but we can also find a better way. We know 
that register Y will contain a non-zero number at this 
point, since we just executed an INY instruction and 
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the initial value in Y was 00, as set at the start of the 
program. In addition, if Y is ever incremented all the 
way up to FF and then to 00 again, the routine will 
proceed to output the first character of the string 
again, and continue. In such a case, the routine will 
run forever, eternally displaying the same 
256-character string. In such a case, the only way to 
regain control of the computer will be to reset it or 
turn it off. 

To avoid any possibility of this occurrence, we will 
put a BNE instruction at location 200B, to return to 
the LDA instruction at LOOP only so long as Y has 
not been cycled back to 00. In this case, we know 
the address of LOOP, so we can calculate the offset 
required by the BNE instruction to get there. To do 
this, we need two addresses: the address of the 
instruction following the branch instruction (200D) 
and the address of the destination instruction 
(2002). Subtract these addresses in hexadecimal, 
with the address of the destination instruction as the 
minuend: 


2002 
- 200D 


FFF5 


The four-hex-digit difference must be in the range 
FF80 through 007F. Any result outside of this range 
indicates that the destination address is too far away 
to make the branch possible. Results beginning with 
FF are negative, and indicate backward branches. If 
the difference starts with 00 it is positive, and the 
branch is forward. In either case, the actual operand 
for the branch instruction is the least significant byte 
of the difference. Thus, our BNE instruction needs 
an operand of F5. 
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This concludes the function of the routine, so we 
can now place our RTS instruction, with the label 
EXIT, at location 200D. 

We have now reached the end of the program, so 
the string will come next. At this point, we know that 
the string will start at address 200E. Therefore, we 
can go back and fill in this address (least significant 
half first!) in the LDA instruction. We can also 
calculate the operand for the BEQ instruction as 
follows: 


200D (destination address) 
- 2007 (address after BEQ instruction) 


0006 (operand will be 06) 


Figure 4-6 shows the program with all operands 
inserted. 

To enter this program, start NRIBUG if neces- 
sary, and type in A 2000<return>. Then, enter the 
the following instruction sequence: 


LDY #$00<return> 

LDA $200E, Y<return> 

BEQ $200D<return> 

JSR $FFxx<return> 

INY<return> 

BNE $2002<return> 

RTS<return> 

<return> 

:200E 48 45 4C 4C 4F 2C 20 57<return> 
:2016 4F 52 4C 44 21 0D 00 00<return> 
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Figure 4-6. Inserting the remaining operands. 


Ordinarily, at this point you would assign a name 
to this program and save it to disk. That way, if you 
did make some error and the program refused to 
halt, you could reset the computer and recover the 
program from disk. In this case, however, it is 
unnecessary to do so; this program is recorded on 
your program disk as HELLOA.COM (A for 
Assembly language). 

To verify that the program works correctly, first 
place a breakpoint at location 200D to replace the 
RTS instruction. Do this with the command B 
200D<return>. Then, type the command: G 
2000<return> to begin execution of the program. 
Does the program display the correct string? 

Because this program ends right here, we can 
extend the character string to any desired length. 
There is no more program that we would otherwise 
overwrite. To demonstrate this, change the char- 
acter string to “HELLO, EVERYONE IN THE 
WHOLE WIDE WORLD!” . You can use either the 
M command or directly use the : command in the 
monitor to accomplish this. Be sure to include the 
CR and null characters at the end of the string. 
Then, demonstrate the operation of the program 
with the G 2000<return> command. 

Now, can we modify the program to delete the 
“Hello,” portion of the string without rewriting the 
entire string? Yes, we can. Change the address in 


“99 


the LDA instruction so that it will point to the “e” in 


“everyone.” Then, change the “e” to “E,” since it will 
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now begin the character string. When you have 
accomplished this, run the program again to check 
its operation. When you are sure that you have the 
correct results, save your new program to disk 
under the name EVERYONE.COM. 

Modifying the compiled or assembled version of a 
program is known as patching the program. This 
approach is used to make small modifications for 
testing purposes, or to delete a section of the 
program that is no longer wanted. This is done by 
replacing the unwanted code with a series of NOP 
instructions. If the deleted code section is large, the 
first instruction can be replaced with a JMP 
instruction to the following section of code. With 
very few exceptions, patching may be used to 
change or to shorten a section of code or data, but 
cannot be used to lengthen the code. 

Code patching is properly used to make minor 
corrections to the program being tested, so that we 
can avoid having to recompile or reassemble the 
entire program many times. However, once these 
small corrections have been confirmed by testing, 
the equivalent corrections should still be made to 
the source code and the program recompiled or 
reassembled. Also, all corresponding documenta- 
tion should be updated to reflect the changes in the 
code. Otherwise, it is too easy to lose track of all of 
your corrections. 

Basically, patching is a procedure for repeated 
modify-and-test or cut-and-try situations. This is the 
procedure used to find just the right sequence or 
just the right method to perform the desired task. It 
is not the procedure to use to produce the final 
version of the program. 
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SIMPLIFYING THE DEBUGGING PROCESS 


The programs we have used for demonstrations 
of debugging procedures have all been quite short, 
at least for the working part of the program. Testing 
and debugging have been straightforward, and have 
been performed on the entire program at once. This 
approach is not practical when the program is thou- 
sands of lines of compiler language source code in 
length. 

As an example of this size program, there is a 
communications program for the IBM PC and com- 
patibles called PIBTERM, which is designed to oper- 
ate any of a number of different “smart” modems 
which can dial a phone number, answer the phone, 
and communicate over telephone lines with other 
modems. It has a wide range of capabilities, and is 
available from a number of BBS’s (Bulletin Board 
Systems) on a Shareware/Freeware basis. It consists 
of a 36K byte COM file plus eight overlay files, 
which range from 4K to 77K in length. The original 
program was written in Turbo Pascal, and¥s more 
than 34,000 lines long in this language. Can you 
imagine just how difficult it would be to debug such 
a program all at once? And, even this is shorter than 
some programs in normal use. 
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With programs this long (and even shorter ones), 
the entire program will not be executed during any 
given run. Conditional instructions will bypass some 
portions of the program, and will cause other por- 
tions to be executed repeatedly. We must find a way 
to test and debug the entire program without having 
to do it all at once. There are some techniques we 
can use to make sure that we thoroughly test the 
entire program without having to just hope that we 
didn’t miss something that will show up later. In this 
Track, we will see how we can be sure of thorough 
testing and debugging. 


Sector 1: Defining Memory, Register, and 
Stack Usage 


Whenever you design and code a program, one 
of the things you must decide is how you will use 
memory, registers, and the stack for the storage of 
data to be used by the program. You can assume 
that data stored in a normal memory location can be 
accessed and modified by any routine or subroutine 
in the program, and by any interrupt service routine, 
if the interrupt routine is so designed. Data stored on 
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the stack is inaccessible to other portions of the 
program. It can be reached, but only by deliberate 
programming to find it. Data remaining within the 
CPU registers is perishable; it will vanish as soon as 
the register is used for another purpose. 

To make the best possible use of all three ways of 
keeping data, some practical techniques have 
evolved. First, main memory is used to store data 
that must be used by the entire program. For exam- 
ple, flags that define operating parameters, ad- 
dresses of assigned buffer spaces, and other similar 
information will usually be stored in normal mem- 
ory. Typically, these values will be set during ini- 
tialization, and will then be left alone. Other portions 
of the program will read this data as necessary, but 
will not modify it. 

The stack is used for temporary storage of data 
and as a workspace within a single routine or sub- 
routine. The most common usage of the stack is as a 
place to save the contents of registers during the 
operation of a subroutine. Data that must be saved 
for use by the calling routine is PUSHed onto the 
stack, thus freeing the register for use by the sub- 
routine. When the subroutine returns control to the 
calling program, the data is POPped back into the 
original registers. This frees up the registers for use 
in transmitting data back and forth between the 
calling program and the subroutine. 

When you design a program along these lines, 
you have a choice of exactly when to PUSH and 
POP the registers on the stack. If you perform these 
actions as part of the subroutine, then you will not 
have to repeat the PUSH and POP instructions each 
time you call the subroutine. If you place the PUSH 
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and POP instructions in the main program, you only 
need to PUSH those registers that you must save 
this particular time. Every subroutine then automati- 
cally has full access to all registers. 

The subroutine is usually given the job of preserv- 
ing all registers that it will use, except for any that are 
used to return information to the calling program. 
This makes the handling of the registers more uni- 
form throughout the program, and simplifies the 
program design requirements. Whichever technique 
you prefer, you must be sure to be consistent, to 
avoid problems in the operation of your program. 


Since you cannot be sure that a particular 
subroutine will be required during any given run of a 
program, one of the easiest ways to make sure that 
each subroutine is tested is to test each one 
individually. You can do this readily by assembling 
or compiling a subroutine by itself, loading it, and 
then using NRIBUG to preset registers and trace 
through program operation as necessary. Or, you 
can load the entire compiled or assembled program, 
and use NRIBUG to locate the various subroutines, 
and execute them individually to check their be- 
havior. 

It is also possible to test individual functions 
within a single subroutine by presetting appropriate 
registers and then setting appropriate breakpoints 
with the B command. Each function can be tested 
individually, and then tested again in conjunction 
with adjacent functions. 

For example, consider a subroutine whose task it 
is to take a 16-bit number, convert this value into 
four hexadecimal digits in ASCII form, and output 
these four digits to the screen in order (most 
significant digit first). As an added bonus, we should 
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be able to enter the subroutine somewhere in the 
middle to allow us to output an 8-bit number as two 
hex digits. We don’t want to ignore leading zeros, 
since that can spoil the format of a hex display. 
Such a subroutine exists within NRIBUG, to 
output addresses and data in the R, D, and M 
displays. Figure 5-1 shows the basic flow chart for 
this routine, tailored for assembly language re- 
quirements. Note that this routine has three per- 
missible entry points, depending on whether you 
wish to output 1, 2, or 4 hex digits. Also, note that 
this routine calls itself internally, in order to output 
multiple digits. Thus, the 4-digit routine first calls the 
2-digit routine as a subroutine, and then falls 
through to the 2-digit routine to output the second 
pair of digits. Likewise, the 2-digit routine first calls 
the 1-digit routine and then falls through to it. This 
technique is commonly used when an identical task 
must be performed more than once. It can save a 
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Figure 5-1. Flow chart for the hex to ASCII output routine. 


large amount of memory space for a small cost in 
increased processing time. 

The single-character output routine is the call to 
location FFD2 as before, and is easy to use. 
However, the “ADD ASCII BIAS” box in the flow 
chart requires a little bit of explanation. This box 
indicates that the 4-bit binary number in the 
low-order end of AL is to be converted to an 
equivalent ASCII code. Hex digits 0 through 9 are 
converted to ASCII codes 30H through 39H. 
However, the next seven ASCII codes are for 
punctuation marks and other symbols. the letter A 
has an ASCII code of 41H. 

If you have only decimal numbers to work with, 
you can simply add 30H to each digit before 
displaying it. This would be the case if you were 
working with BCD numbers. However, if you will be 
using hexadecimal numbers, you must find a way to 
selectively add 07 to the result, if you have a hex 
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code A through F. Several methods have been 
evolved to accomplish this, and we will look at one of 
the most cunning techniques shortly. 

The complete subroutine is on your program 
disk, with the filename HEX2ASC.COM. If you try 
to run this program all by itself, you will simply see a 
four-hex-digit display (the contents of locations C1 
and C2), and get the system prompt back again. 
Keep in mind that this is not intended to be a 
stand-alone program; it is simply a subroutine. 

Load this subroutine into your computer, so that 
you can use NRIBUG, examine it and explore its 
operation. Do not run the subroutine yet. First, use 
the D command to look over the overall routine. It 
begins at location 3000 hex. Figure 5-2 shows the 
source code you should see. 

Comparing Figure 5-2 with Figure 5-1, we note 
that there are three separate entry points, according 
to how many digits are to be displayed. These occur 
at locations 3000 (4-digit entry point), 3007 (2-digit 
entry point), and 3010 (1-digit entry point). The two 
JSR instructions in the listing also show the second 
and third entry points. 

Since this routine has multiple entry points, we 
will test the innermost loop first. This is the simplest 
path, and contains no interactions with the re- 
mainder of the routine. Also, this is where the actual 
conversion takes place and the character is sent out 
to be displayed. 

The conversion of a 4-bit binary number (one hex 
digit) to ASCII format can be performed in any of 
several ways. The ASCII codes for digits 0 through 
9 are 30 through 39 hex. Therefore, we can simply 
add 30 hex to the 4-bit number, and (if it is one of 
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Figure 5-2. An unassembly listing of HEX2ASC.COM. 


these digits) the job is done. However, the ASCII 
codes for letters A through F are 41 through 46 hex. 
This leaves a gap of seven codes between the digits 
and the letters. Therefore, we must test for the 
possibility that we have a letter instead of a digit, and 


add 7 if this is the case. The resulting routine looks 
like this: 


ADD #$30 
CMP #$3A 
BMI DONE 
ADD #$07 
DONE: (program continues here) 
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Sometimes the test is done first, in which case the 
routine looks like this: 


CMP #$0A 
BMI DIGIT 
ADD #$07 
DIGIT: ADD #$30 
(program continues) 


However, comparisons and conditional jumps 
take extra time and memory space. One of the goals 
of all programmers is to improve the efficiency of 
programs as much as possible. This is especially 
important for high-speed programs that must op- 
erate in real time, but it is also desirable in general. 
Therefore, the authors of NRIBUG used a different 
approach, which requires no tests and no condi- 
tional jumps. 

This approach makes use of decimal (BCD) 
arithmetic. This mode of operation in the 6502 
checks the result of each ADC and SBC instruction, 
and adds or subtracts 6 to each BCD digit of the 
result if necessary, to keep the result in correct BCD 
format. To see how this works, let’s look at the 
conversion code that we use, and which is used in 
NRIBUG: 


SED 

CLE 

ADC #$90 

ADC #$40 

CLD 

(program continues here) 
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Keep in mind that A starts with only one hex digit 
in the least significant bit positions. Thus, A starts 
with a value from 00H through OFH. When we add 
90H, therefore, A should contain a value from 90H 
through 9FH. 

However, we used the SED instruction to set the 
decimal operating mode. If the least significant digit 
in Ais in the range 0 through 9, it is a valid BCD digit, 
and nothing will happen to it. In addition, the 
high-order digit is 9, and is therefore legitimate BCD. 
Therefore, it will remain this way. One important 
factor to note is that in adding 90H to A, we had no 
carries, either from the low-order digit position to 
the high-order digit (half-carry, H) or from the 
high-order digit (full carry, C). Thus, if we had a 
number from 0 through 9 in A, we will wind up with 
a number from 90 through 99 in A. 

The second ADC instruction will now find no 
carry, so it will add 40H to the value in A. The 
resulting number will be in the range DOH through 
D9H. But D is not a legitimate BCD number. 
Therefore, the CPU will add 60H to A. This will leave 
30H through 39H in A, and produce a carry. We can 
ignore the carry, and note that the value in A is the 
correct ASCII code for one of the digits 0 through 9, 
according to whatever was originally in A. 

But what if A contained 0AH through OFH? In 
that case, the first ADC instruction will add 6 to the 
least significant digit, producing a number from 0 
through 5 in this position, and a carry to the 
high-order digit. This carry in turn increases the 9 to 
$A. This is not valid BCD, so that first ADC 
instruction also adds 6 to this digit, producing a 0 
digit and a carry. Thus, following the first ADC 
instruction we will have a carry and a result in the 
range 00 through 05. 

When we add 40H with the carry, we will have a 
number in A between 41H and 46H. All numbers in 
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this range are valid BCD numbers, so there will be 
no further adjustment for BCD, and we will be left 
with the correct ASCII code for the letters A 
through F. 

Thus, this sequence of instructions will perform 
the conversion of a single hex value in A to the 
equivalent ASCII code, without using any condi- 
tional instructions or extra program bytes. 

The character display routine is the same 
CHROUT routine we used before, at FFD2 in the 
jump table. This routine simply outputs the char- 
acter in A, so we need not move the character just 
developed. We can call the output routine directly. 

To see this routine in operation, use the R 
command to set A to each value from 00 through OF. 
Use B to set a breakpoint at location 301C. Now, 
use the G command to execute just the portion of 
the routine that starts at address 3010. Note that 
each binary value is correctly converted to the 
ASCII code for the corresponding hex digit. 

We cannot use the same technique to test the 
two-digit entry to this subroutine, because the 
breakpoint will terminate execution after the first 
character has been displayed. Therefore, to test the 
remainder of the subroutine, use the A command of 
NRIBUG to assemble a short test routine at address 
2FFO, as follows: 


LDA #$00 
JSR $3007 
BRK 


Also, use the B command by itself to restore the 
RTS instruction at the end of the subroutine we are 
testing. 
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Now, to test the two-digit capability of the 
subroutine, use either the M or : commands to 
change the initial value to be loaded into A (at 
address 2FF1), and then use G 2FF0<return> to 
execute the test routine. As you try different values 
in A, does the routine correctly display the appro- 
priate 2-hex-digit number? 

Once you have determined that the 2-digit 
routine starting at 3007 works correctly, test the 
entire routine as a unit. To do this, first modify the 
test code at 2FF0 to JSR to address 3000. Also, it will 
no longer be necessary to use the LDA instruction, 
since the overall routine will get its data from 
memory. Accordingly, place any desired 4-digit hex 
number at locations Cl and C2 in the Zero Page 
(remember to insert the value least significant byte 
first). Then, use the G command to execute the 
entire routine, using the test code at address 2FFO. 

Wait a moment! What happened here? That 
wasn’t the correct data! What went wrong? Actu- 
ally, this is an example of a classic problem in 
computer programming: both our routine under 
test and NRIBUG are using these particular mem- 
ory locations. Therefore, NRIBUG changes them 
before it actually executes your routine. The result 
is that our subroutine does not receive the data we 
intended, but rather the last data placed there by 
NRIBUG. This data is determined strictly by 
NRIBUG, rather than by our data entry. 

To solve this problem, there are several ap- 
proaches we might take. A very practical routine is 
to place the initial data in registers (perhaps A and 
X) rather than in memory. That way, there can be 
no interference between different routines. An 
alternative, which we will use for the present test, is 
to have the test routine insert the desired data into 
C1 and C2 before calling the subroutine. To 
accomplish this, assemble the following at 2FFO: 
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LDA #$55 
STA $C2 
LDA #$AA 
STA $Cl 
JSR $3000 
BRK 


Test the routine by placing the high-order byte to 
display as the operand of the first LDA instruction, 
and the low-order byte as the operand of the second 
LDA instruction. Now, the routine should work 
correctly. 

Continue to test this routine until you are sure 
that it will correctly display all four hex digits for any 
combination of letters and digits in any order. 

The HEX2ASC.COM subroutine has already 
been tested and fully debugged. Therefore, it should 
have performed in accordance with the description 
above. 

The inner (1-digit) routine performs as described 
above. The AND instruction zeros out the high- 
order half of A, so that only one hex digit will be 
converted at a time. The conversion to ASCII and 
the call to display the character then proceed in a 
straightforward manner. 

The 2-digit routine uses four LSR instructions to 
move the high-order half of A to the low-order 
position. It then calls the 1-digit routine to output the 
high-order digit. 

The 4-digit routine also works correctly. It simply 
uses the 2-digit routine twice; once for the highorder 
byte and then again for the low-order byte. 
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Sector 3: Building a Program Library 


Many programs, routines, and subroutines can be 
used in more than one application. For example, the 
specialized input routine that we used in our 
CHECKBOOK program applied also to PHONE- 
BOOK, with only slight modifications. The same 
holds true for various procedures written in other 
languages. 

If you save your tested and debugged subroutines 
and functional routines in a “library” of programs, 
you will have them available to you without having 
to rewrite them each time you need them. You can 
include them in any program requiring those partic- 
ular functions. You already know that they work 
correctly, so you need not debug them individually 
again. 

As part of your subroutine library, be sure to state 
explicitly what variables or registers are required by 
the subroutine, what data it requires as inputs, and 
what it provides as outputs. Specify what changes it 
makes to various variables or registers, so that it 
won't inadvertently cause a problem elsewhere in 
your main program. 

Be sure to test the program as a whole, with all of 
the debugged routines and subroutines in place. 
Unsuspected interactions between apparently unre- 
lated routines can totally ruin the operation of an 
otherwise perfect program. 


As your subroutine library grows, you will find 
that you not only gain programming experience, 
but you will also be able to take more functions from 
your library, leaving less mechanical work to be 
done in the design of new programs. The design of a 
new program will involve more creativity and less 
drudgery as you continue to work with your com- 
puter. 
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PRACTICE PROBLEMS 


At the end of Module 5, you did a substantial 
amount of experimental work with your computer. 
Some of the instructions you tried seemed to have 
no effect, while others gave weird results or else 
caused the operating system to lose control of the 
computer. However, you should have found that 
most instructions performed as their names sug: 
gested, and caused no problems. To see what 
happened as you performed various individual 
instructions, let’s take another look at the instruc- 
tion set for the 6502 microprocessor. 


Sector 1: The 6502 Instruction Set and Ad- 
dressing Modes 


The 6502 is a memory oriented microprocessor. 
This means that it is intended for the most part to 
keep its data in memory, rather than in its few 
internal registers. Most instructions are designed to 
use data in memory, and the instruction set includes 
a variety of addressing modes, or methods which 
can be used to find the required data in memory. 
The 6502 includes the following ways of locating 
data in memory: 
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Address alone: zero page 
absolute address 

Indirect addressing: (ADRS) 

Indexed addressing: ADRS,X 
ADRS, Y 

Indirect indexed addressing: (ZP,X) 

Indexed indirect addressing: (ZP),Y 


As you discovered when you tried various 
instructions using all of these addressing modes, the 
behavior of the instruction itself was not affected by 
the method used to find the data required. An ADC 
instruction correctly added the source operand to 
the accumulator contents and modified the flags 
register, regardless of the addressing method used 
to find the source value. 

The condition flags are modified by various 
instructions to reflect the results of arithmetic or 
logical calculations. The conditional jump instruc- 
tions can then be used to alter the sequence of 
program execution, based on these condition flags. 
You learned this much in Module 5. However, in 
order to use the conditional jump instructions 
effectively, you must know which flags are affected 
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by which instructions and exactly what each flag 
means. This was one of the primary purposes of that 
tedious exercise. 

Figure 6-1 shows the instructions that can affect 
the flags, and which flags may be affected by which 
instructions. The flags that you will normally be 
concerned with are Carry, Zero, Sign, and Over- 
flow. Of these, the first three are fairly self-explan- 
atory. The Carry flag indicates that an arithmetic 
operation produced a borrow (subtract) or a carry 
(add), or is used to hold the bit that is shifted out of 
an operand by a shift or rotate operation. You can 
think of it as a one-bit extension to any operand that 
permits one operand to be linked to another in 
successive operations. 

The Zero flag is set if the result of the latest 
operation was exactly zero. This may be any 
arithmetic or logical operation. This includes LDA 
and PLA instructions. However, STA and PHA 
operations will not affect the flags. 

The Sign flag indicates a negative result. This 
assumes two’s complement arithmetic, in which the 
most significant bit of an operand indicates the sign 
of that operand. If it is set, the number is assumed to 
be negative and in two’s complement form. Thus, 
the Sign flag is simply a copy of the most significant 
bit of the result of an operation. 

The Overflow flag applies only to two’s comple- 
ment arithmetic, and indicates that a two’s com- 
plement overflow has occurred. This indicates that 
the indicated sign of the result is incorrect, and that 
the real sign bit is in the Carry flag. An overflow can 
also occur during rotates and shifts, if the result of 


the shift changes the sign of the operand. Of course, 
if you are dealing with unsigned numbers or 
individual bits in logical manipulations, the Overflow 
flag does not apply. 

As we mentioned above, not all of the 6502 
instructions affect the condition flags. Figure 6-1 lists 
only those instructions that do modify one or more 
flags. It is very important when setting up a 
conditional operation to be absolutely sure that you 
know the nature of the selected condition, and how 
the jump will behave. If you are at all unsure of which 
conditional jump instruction to use or under what 
circumstances the CPU will take the jump, use 
NRIBUG to trace through the critical sequence of 
instructions and find out how the computer will 
respond according to the original operands and the 
result of the operation. Modify the comparison (if 
any) and the jump instruction, as necessary, to 
make sure that the jump will be taken only when 
necessary, but that it will always be taken when it 
should. 

There were two types of instructions that may 
have caused your computer to either go to sleep or 
to exit the program as if you had pressed the 
RUN/STOP and RESTORE keys. These instruc- 
tions transferred control to an address not under 
your control. For example, the RTS instruction 
takes its destination addresses from the stack. If you 
did not preset the SP register or stack contents 
before each test, you may have found your com- 
puter trying to execute random garbage at some 
unknown location in memory. The RTI instruction 
also pulls the flags register from the stack. In either 
case, these instructions are intended to be used only 
after a JSR instruction or an interrupt has been 
generated to place the needed return address and 
data on the stack. It is possible to use these 
instructions to control the program execution 
sequence, but caution is required. 
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is unchanged by the instruction 

may be changed by the instruction 

is always set by the instruction 

is always cleared by the instruction 


Figure 6-1. The 6502 instructions which affect the flags. 
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Sector 2: The Solution from Module 5 


The string display problem from Module 5 was 
deliberately arranged to require a character string 
that would occupy more than one line of the display. 
In fact, this string occupies five to six display lines on 
a 40-column display. This requires that the string be 
formatted with carriage return/line feed codes, in 
order to make sure that no words will be wrap 
around from one side of the display to the other. 

Since this was to be a program designed from 
scratch, you should have started from the very 
beginning of the programming process. We stated 
the requirements for the program in detail, so the 
next step is to draw up the flow chart (or any other 
type of diagram) for the program. In this case, the 
program itself is very straightforward. Only the 
string itself is long. Figure 6-2 shows the resulting 
flow chart. 

With the flow chart drawn, we can now code the 
program. Since this is to be in assembly language, 
we will use a coding form. The coded program, 
before we assign any addresses to the instructions, 
is shown in Figure 6-3. This time, we will begin our 
program at address 4000. Therefore, we can assign 
instruction addresses and op codes as shown in 
Figure 6-4. Since we don’t know at first where the 
string will begin, we don’t know what address to use 
in the LDA indexed instruction. However, we do 
know that the entire instruction will require three 
bytes, so we can proceed to assign addresses to it 
and all succeeding instructions. 
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RESET Y TO 28 


GET CHARACTER 
USING INDEXED 
ADDRESS ING 
FROM BASE ADDRESS 
OF STRING 


DISPLAY THE 
CHARACTER 


INCREMENT 16-BI 
BASE ADDRESS 


1s 
RESULT 
ar 


CO RETURN > 


Figure 6-2. The flow chart for the string display 
program. 


This routine performs the same task as the 
assembly-language HELLO program we examined 
earlier. However, we have chosen in this case to use 
a slightly different technique for outputting the 
string. Rather than using a fixed base address to 
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PROGRAM pe a PAGE 1 OF1 | 
Ose. =--—d 
D E jy 


a Se 
jl aS Se ee ee 
ee eh ee 
SSS Se Se ae ae eae ees Stes 
SSS SS Se Sa ee Se Se ee Caines aoe eee 
SS Bae Se ee ee eee eee ee ee 


Figure 6-3. Writing the assembly-language program. 


PROGRAM NAESSAGE 
aes 
A B Cc D E F G H | J 
CES A CN TT A SS 


oe. aes Se BE a a ae RE Seen Se 
ee ee 


Figure 6-4. Inserting op codes and instruction addresses. 
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eee 
A B Cc D E F G oH fl J 
Eire: Sb josie oe eles Re) oe So ee dO eee Ree nee See eS 
eens ag fs cer: | En TRIN | eee 
Cae ee oe 


Sees 
Ayer NE Oe ee ee 
Og eT a 
Epes Se ee 


point to the start of the string and then stepping the 
index pointer (Y), this time we have left Y with a 
value of 00, and we are incrementing the 16-bit base 
address. This technique has both advantages and 
disadvantages over the method we showed earlier, 
where we incremented Y. 

The advantage is that we are now performing a 
16-bit increment of the base address, so we can now 
handle strings longer than 256 characters. However, 
at the same time we have the disadvantage that the 
base address within the program is being perma- 
nently changed by the program itself. Therefore, 
this program cannot be run again, until the base 
address of the string has been reset. This arrange- 
ment is known as “self-modifying code,” and is 
generally considered to be poor programming 
technique. There are special cases where this type 
of code is acceptable or even desirable, but these 
cases are relatively few. Alternative methods are 
very much to be preferred in most circumstances. 

Figures 6-3 through 6-5 show the evolution of the 
hand assembly of this program. Note that if you use 
the A command of either NRIBUG or the monitor 
within FAS, the assembler will calculate the pro- 
gram offsets for you, although you will have to insert 
the addresses of EXIT and STRING. In addition, if 
you use FAS, that monitor has a few extra com- 
mands, not available in NRIBUG. For example, it 
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Figure 6-5. Resolving the forward references. 


“0 


has a “/” command, used just like “:,” except that it 
allows you to enter ASCII text rather than hex data. 
Of course, you must use “:” to insert the initial 
clear-screen code (93) and CR codes. After that, 


however, you can use the “/” command in the form: 


/4020 PROGRAMMING IN ASSEMBLY<return> 
/4037 LANGUAGE DOES NOT HAVE<return> 


and so on. Use the M command to locate the last 
character already entered. Trailing spaces will be 
ignored, so they must be inserted at the start of the 
line. The space after the address is not stored in 
memory. 

If you set up the string to occupy five or six lines 
of the display, you will need ten CR codes to center 
it on the screen. You can adjust this number as 
necessary to position the display more precisely. In 
any case, the last character in the string must be the 
null character. Thus, your last entry line should use 
the M command to insert a 00 after the final period. 

This program is included on the enclosed pro- 
gram disk with a filename of MESSAGE.COM. To 
run the program, load it with the “,1” option. Then 
use the SYS command to execute the program at 
address 16384 ($4000). Or, load the program and 
execute it under either NRIBUG or the FAS 


monitor. 
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paoGRan STRING DISPLAY ROUTINE 
pees 


Sra [srr ew ace 
eae ma Be Sees ee 


ass 

= ee ee ee ee 

SS FAT Se ee es is ee eas eee SS eS 
STE Gal 70 Sel BS ee a Ba oe Eee 
ees a eee PC STEP Bale ApDRE|ss PAST [CounT | 
2G RES 2 a eee es ee See ees 
RSs ae is Cee eee Bee Gane ES eee Se 
Fo OAS ce a Saal to a Ss Ae See ieSe ee ee 
BBR eee ek yor ee a OEE BSS, eemeeed ans oe ne eee 
JSS Sars fokdel do: sei ae RE ea oo ae a 
INC. a eS bees et aa SS 


Check the operation of the program under one of 
the monitors. If your version of this program split a 
word around the edge of the screen, you should 
have rewritten the string to break the lines at 
different points, so that all words remained intact. 

Because the null character is required to termi- 
nate the string, there is no way that the string can 
contain this character. The null cannot be displayed 
at all using this method. Fortunately, it is seldom 
required. However, a slow printer or other periph- 
eral device (unlikely, but possible, with modern 
technology) may require a few nulls at the end of 
each line to delay the computer briefly. To accom- 
plish this, it is necessary to rewrite the subroutine to 
either terminate on a different character, or else use 
a predefined count and output any characters at all. 
You will work with such a subroutine in the next 
sector. 
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Figure 6-6. The subroutine to be tested and corrected. 


Sector 3: A Problem for Next Time 


Figure 6-6 shows an assembly-language subroutine. 
The purpose of this subroutine is to display on the 
screen any character string of any length, including 
the null character. It assumes the following inputs: 


1. The character string begins with a 16-bit count, 
to tell the subroutine how many characters are in 
the string. 


2. Registers A and X point to that count, which will 


be immediately followed in memory by the string 
itself. A contains the high-order half of the 
address. 


Upon return, the subroutine must restore the 
original contents of any register it used. This 
includes A and X, which will remain pointed to the 
string count word. 
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The intent of this subroutine is to first save all 
registers that it will use, and then to establish all of 
the conditions it will require. After this is done, it is 
to read the count, and then display the character 
string itself. The subroutine will not attempt to 
format the string in any way; that is the job of the 
programmer using the subroutine. 

The technique used here is to keep a copy of both 
the string address and the count on the stack, where 
they can be accessed by indexed addressing 
through X with the help of the TSX instruction. 

There is only one problem: this subroutine 
doesn’t seem to work correctly. It won’t even 
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assemble correctly into memory. Your practice 
problem for the next module is to use NRIBUG to 
assemble this subroutine into memory, add what- 
ever code you need to test its operation, and to 
make whatever corrections may be required. When 
you have the subroutine working correctly, save it 
to disk. 

You may wish to use other function calls through 
the jump table at the top of ROM. To help you with 
this, Figure 6-7 shows the function calls in the jump 
table at the top of ROM that you might use in your 
programs. Each of these calls requires data to be 
passed to it in one or more CPU registers. Figure 
6-7, on the next three pages, shows the information 
passed back and forth between these routines and 
your programs, and the registers used to pass this 
information. 

In your next module, we will describe the 
problem(s) with this particular subroutine, and see 
how it can be made to work correctly. 
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ADDRESS 
$FFS1 


$FF 84 


$FFQ7 


$FFSA 


$FFSD 


$FF9O 


$FFOS 


$FF9L 


$FF99 


$FFOC 


$F FOF 


$FFA2 


$FFAS 


$FFAS 


$FFAB 
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NAME 
CINT 


IOINIT 


RAMTAS 


RESTOR 


VECTOR 


SETMSG 


SECOND 


TKSA 


MEMTOP 


MEMBOT 


SCNEEY 


SETTMO 


ACPTR 


CIOUT 


UNTLE 


FUNCTION 
Initialize the screen editor. No input required. Modifies 
A, X, and Y. 


Initialize I/0 devices. No input required. Modifies A, X, 
and Y. 


Perform RAM test, set screen and cassette buffers. Sets top 
and bottom memory pointers. Modifies A, X, and Y. 


Restore default I/0 vectors. Modifies A, X, and Y. 


Copies system vector addresses into and out of the RAM 
vector table. X and Y point to user space in RAM 
(high-order half in Y). C flag indicates direction of copy. 
Modifies A, X, and Y. 


Controls the use of system message output. Uses bits 6 and 
7 of A to control source of messages (4 enables control 
messages, 7 enables error messages). A is modified. 


Send secondary address after LISTEN. Send the byte in A as 
a secondary address or command to an I/O device after it 
has been sent a LISTEN command. 


Send secondary address after TALK. Send the byte in A as a 
secondary address or command to an 1/0 device after it has 
been sent a TALK command. 


Read or set the top of memory. Use Y (high-order) and X to 
read (carry set) or set (carry clear) the top of user RAM. 
Modifies X and Y. 


Read or set the bottom of memory. Works just like MEMTOP, 
but will read or set the bottom of user RAM. Modifies X and 
VY. 


Scan the keyboard. Return the ASCII code of the pressed key 
in A. If no key pressed, return 00 in A. Also modifies xX 
and Y. 


Set timeout on IEEE bus. Uses A to set (non-zero value) or 
reset (zero) the 64 millisecong timout timer on the IEEE 
bus, if used. 


Accept a byte in A from the serial bus. TALK (and possibly 
TESA) must be called first. Modifies A and X. 


Output a byte in A to the serial bus. LISTEN (and possibly 
SECOND) must be called first. Does not modify registers. 


Command an 1/0 device on the serial bus to stop talking. 
Modifies register A. 
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Figure 6-7. The jump vectors at the top of the kernal ROM. 
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$FFAE 


$FFE1 


$FFE4 


$FFB7 


$FFBA 


$F FED 


$FFCO 


$FFCS 


$F FCS 


$FFC9 


$FFCC 


$FFCF 


$FFD2 


$FFDS 


a4 


UNLSN 


LISTEN 


TALK 


READST 


SETLFS 


SETNAM 


OPEN 


CLOSE 


CHE IN 


CHEOQUT 


CLRCHN 


CHRIN 


CHROUT 


LOAD 


gle’ Smekt pot, see! a alta 6: 


Command an 1/0 device on the serial bus to stop listening. 
Modifies register A. 


Command a device (device number © - 31 in A) to prepare to 
receive data. Modifies A. 


Command a device (device number 0 - 31 in A) to prepare to 
transmit data. Modifies A. 


Read the status word. Returns the current 1/0 status byte, 
indicating any errors, in A. X and Y are not affected. 


Set logical file number (in A), device number (in X) and 
secondary address/command (in Y). Set Y to $FF if no 
secondary address is to be sent. This routine is a 
preliminary to other kernal routines. 


Set the filename for LOAD, SAVE, and OFEN routines. A 
contains the length of the name string, while X and Y 
(high-order half) contain the address of the string. 


Open a logical file. Both SETLFS and SETNAM must already 
have been called. Modifies A, X, and Y. 


Close a file (logical file number in A). Modifies A, X, and 
Nie 


Open a channel for input. X contains logical file number. 
Establishes a communications channel between an input 
device or already OPENed input file and the CPU. 

Modifies A and X. 


Open a channel for output. Same as CHKIN, except for output 
instead of input. 


Clear all 1/0 channels. Closes all open channels, and 
restores default communications with keyboard and screen. 
Modifies A and X. 


Input a character from the currently open channel (default 
is the keyboard). Character is returned in A, X is 
modified. 


Output character in A to current output channel (default is 
screen). A is modified. 


Load RAM from a device. SETLFS and SETNAM must already have 
been called. Load (A = 0) or verify (A = 1) RAM from 
external device. If secondary address for SETLFS is 00, the 
address information in the file header is ignored, and Y 
(high-order half) and X contain the starting address in 
RAM. Modifies A, X, and Y. 


Figure 6-7. cont. The jump vectors at the top of the kernal ROM. 


MODULE 6 


Testing and Debugging Made Easy a: areas aa or 


$FFD8 


$FFDB 


$FFDE 


$FFE1 


$FFE4 


$FFE7 


$FFEA 


$FFED 


$FFFO 


$FFFS 
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SAVE 


SETTIM 


RDTIM 


STOP 


GETIN 


CLALL 


UDTIM 


SCREEN 


PLOT 


TOBASE 


Save RAM to a device. SETLFS and SETNAM must be called 
first. X (low) and Y (high) contain the address of the byte 
immediately following the last byte to be saved. A contains 
the offset of an address in the Zero Page, where the 
location of the first byte to be saved is stored. 


Set the real-time clock. A (MSB), X, and Y (LSB) contain 
the new contents of the real-time clock, in "jiffies" 
(1 jiffy = 1/460 second). 


Read the real-time clock. The registers have the same 
meanings as for SETTIM. 


Scan the keyboard for the STOF key only. If STOF key is 
pressed, returns with Z flag set. Modifies A and X. 


Get a character from the keyboard input queue. This 
arrangement lets the computer register keystrokes even 
while executing other commands. May modify A, X, and Y. 


Clase all channels and files. Automatically calls CLRCHN to 
clear any open channels on the serial bus. Modifies A and 
X. 


Update (increment) the real-time clock. This routine should 
be called if the user program handles its own interrupts. 
Modifies A and X. 


Return the number of character rows (Y) and columns (X) on 
the screen. Can be used to help determine which machine is 
being used to run a program. 


Read (carry set) or set (carry clear) the cursor location 
on the screen, using X (row 0-24) and Y (column 0-39). 


Set Y (high) and X (low) to the base address of the memory- 
mapped 1/0 devices in the computer. Provided to allow 
upward compatibility for user programs. 


Figure 6-7. cont. The jump vectors at the top of the kernal ROM. 
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